GeMA
The GeMA main application
Loading...
Searching...
No Matches
Cell mesh object methods

Most used:

Index:

Cell geometry methods

mesh:numCells()
Description: Returns the number of cells in this mesh (elements for an element mesh).
Parameters: None.
Returns: Returns the number of cells in the mesh.

Example:

local ncells = m:numCells()


mesh:numActiveCells()
Description: Returns the number of active cells in this mesh. Inactive cells do not take part in analysis processes. A cell can be marked as active or inactive by calling the cell:setActive() method over a cell object returned by mesh:cell().
Parameters: None.
Returns: Returns the number of active cells in the mesh.

Example:

local nactive = m:numActiveCells()


mesh:cell(index)
Description: Returns a cell object given its id in the mesh.
Parameters: index - The cell id number (an index between 1 and mesh:numCells()).
Returns: Returns the cell object.

Example:

local c = m:cell(1) -- Returns the first cell mesh object


mesh:numCellTypes()
Description: Returns a table specifying the number of cells in the mesh for each cell type.
Parameters: None.
Returns: Returns a table indexed by cell type name (see Element types), with the number of cells in the mesh for each type. Entries for cell types that are not present in the mesh are not filled (value equals nil).

Example:

-- Print the number of "quad4" and "tri3" elements in th mesh
local types = m:numCellTypes()
print('quad4', types.quad4)
print('tri3', types.tri3)


mesh:numActiveCellTypes()
Description: Returns a table specifying the number of active cells in the mesh for each cell type.
Parameters: None.
Returns: Returns a table indexed by cell type name (see Element types), with the number of active cells in the mesh for each type. Entries for cell types that do not have active cells in the mesh are not filled (value equals nil).

Example:

-- Print the number of active "quad4" and "tri3" elements in th mesh
local types = m:numActiveCellTypes()
print('quad4', types.quad4)
print('tri3', types.tri3)


mesh:maxNumCellNodes()
Description: Returns the maximum number of nodes in a mesh cell (equivalent to calculating the maximum of the number of nodes of each type that has a non nil entry in the table returned by mesh:numCellTypes()).
Parameters: None.
Returns: Returns the maximum number of nodes among types present in the mesh.

Example:

local maxNodes = m:maxNumCellNodes()


mesh:maxNumCellGhostNodes()
Description: Returns the maximum number of ghost nodes in a mesh cell. Depending on the mesh implementation, this number might be an upper limit, meaning that no cell has more than the returned number of ghost nodes, but without implying that there is a cell with that number.
Parameters: None.
Returns: Returns the maximum number of ghost nodes among cells present in the mesh.

Example:

local maxGhostNodes = m:maxNumCellGhostNodes()


mesh:maxTotalNumCellNodes()
Description: Returns the maximum number of regular + ghost nodes in a mesh cell. Depending on the mesh implementation, this number might be an upper limit, meaning that no cell has more than the returned number of nodes, but without implying that there is a cell with that number.
Parameters: None.
Returns: Returns the maximum number of regular + ghost nodes among cells present in the mesh.

Example:

local maxNodes = m:maxTotalNumCellNodes()


mesh:addCells(numCells)
Description: Adds the specified number of cells to the mesh, whithout initializing their nodes or properties. After calling this function, make sure to initialize cell node lists and properties by calling cell:setNodes() and cell:setProperties() for each added cell. Attribute values for the new cells are initialized with their respective default values.
IMPORTANT: When adding cells to the mesh, if at all possible, avoid calling this function several times in a sequence. Calling it once with the total number of cells is much more efficent than calling it repeatedlly with just a few cells. If cells are added during the simulation loop, please remember to call mesh:emitMeshChanged(). This function can only be called if mesh:hasCapability("addCells") returns true.
Parameters: numCells - A table defining the number of cells to add, grouped by cell type. The given table should be keyed by the cell type name (see Element types) and have as values the number of added cells for each type. Notice that cells are added to the mesh in the order defined by the GmCellType enumeration, i.e., if the numCells list defines that we want 10 new "quad4" elements and 20 new "tri3" elements, all the "quad4" elements will be added before the "tri3" elements since "quad4" appears before "tri3" in that enumeration. For a finer control of the cell creation order, consider calling this function multiple times, each one with a single type entry in the numCells table.
Returns: Returns the index of the first new included cell.

Example:

-- Add 10 quad4 and 20 tri3 elements to the mesh
local ntypes = {quad4 = 10, tri3 = 20}
local pos = m:addCells(ntypes)
-- Init quad4 cells
for i = 1, 10 do
local c = m:cell(pos)
pos = pos + 1
... -- Fill lists with cell nodes and properties
c:setNodes(elementNodesList, m)
c:setProperties(elementPropertiesList, m)
end
-- Init tri3 cells
for i = 1, 10 do
local c = m:cell(pos)
pos = pos + 1
... -- Fill lists with cell nodes and properties
c:setNodes(elementNodesList, m)
c:setProperties(elementPropertiesList, m)
end
m:emitMeshChanged()


Cell topology methods

mesh:adjacentCell(cellIndex, sideIndex)
mesh:adjacentCell(cell, sideIndex)
Description: Given a cell (defined either by its index or by a cell object) and a cell side index (edge index for surface elements or face index for solid elements, undefined for line elements), returns the adjacent cell by that side or nil if that side is at the mesh border. Also returns the index of the neighbor side in the adjacent cell.
IMPORTANT: This function should only be called if mesh:hasCapability("topology") returns true.
Parameters: cellIndex The cell id number (an index between 1 and mesh:numCells()).
cell The cell object.
sideIndex The index of the side whose adjacent neighbor will be queried. It should be an edge local index (a value between 1 and geometry:numEdges()) for surface elements and a face local index (a value between 1 and geometry:numFaces()) for solid elements. See the Element types page for the edge and face organization for each cell type.
Returns: Returns the adjacent cell object or nil if the edge or face is on the mesh border. If there is an adjacent side, also returns the index of the neighbor side at the adjacent cell.

Example:

-- Get the adjacent cell to the second edge of the first mesh cell
local adjCell, adjCellSide = m:adjacentCell(1, 2)


mesh:nodeAdjacentNodes(nodeIndex, options)
Description: Returns a list with the set of nodes that are adjacent to the given node. Nodes are considered adjacent if they are connected by an edge. Each list entry is a node index (a value between 1 and mesh:numNodes()).
IMPORTANT: This function should only be called if mesh:hasCapability("topology") returns true.
Parameters: nodeIndex The node index (a value from 1 to mesh:numNodes() - the given node can not be a ghost node).
options An optional string parameter defining the behaviour of the function when applied over a node from a quadratic element. If equal to "star" (the default if the parameter is ommited) and nodeIndex is a cell vertex, the adjacent nodes will be other cell vertices, ignoring any quadratic nodes between them. If equal to "qstar", the quadratic nodes on the edges leaving nodeIndex will be returned instead. If nodeIndex is itself a quadratic node in the middle of an edge, the edge endpoints will be returned independently of the selecetd option. For quadratic mid surface or mid volume nodes, an empty list will be returned. Extra dof nodes (or flow nodes) on interface elements behave like quadratic nodes and are subject to the options parameter.
Returns: Returns a list (table) with the set of adjacent nodes. Will return an empty list if the node does not belong to any element or if it belongs only to a bar on a surface mesh, or to a bar or surface element on a solid mesh.

Example:

-- Print the set of nodes adjacent to node 5
local adjacentNodes = m:nodeAdjacentNodes(5)
for i = 1, #adjacentNodes do
print(adjacentNodes[i])
end


mesh:nodeAdjacentCells(nodeIndex)
Description: Returns a list with the set of cells sharing the given node. Each list entry is a cell object.
IMPORTANT: This function should only be called if mesh:hasCapability("topology") returns true.
Parameters: nodeIndex - The node index (a value from 1 to mesh:numNodes() - the given node can not be a ghost node).
Returns: Returns a list (table) with the set of cell objects including the given node on their definition. Will return an empty list if the node does not belong to any element or if it belongs only to a bar on a surface mesh, or to a bar or surface element on a solid mesh.

Example:

-- Print the set of cells adjacent to node 5
local adjacentCells = m:nodeAdjacentCells(5)
for i = 1, #adjacentCells do
print(adjacentCells[i]:id())
end


mesh:edgeAdjacentCells(cellIndex, edgeIndex)
mesh:edgeAdjacentCells(cell, edgeIndex)
Description: Given a cell (defined either by its index or by a cell object) and a cell edge index, returns the list of cells including that edge. The original input cell is added to the list. For surface meshes, this is simmilar to calling mesh:adjacentCell().
IMPORTANT: This function should only be called if mesh:hasCapability("topology") returns true.
Parameters: cellIndex The cell id number (an index between 1 and mesh:numCells()).
cell The cell object.
edgeIndex The index of the edge whose adjacent cells will be queried. It should be an edge local index (a value between 1 and geometry:numEdges()). See the Element types page for the edge organization for each cell type.
Returns: Returns a list (table) filled with the set of adjacent cell objects.

Example:

-- Get the adjacents cell to the second edge of the first mesh cell
local adjCells = m:edgeAdjacentCells(1, 2)


mesh:edgeAdjacentCellsFromNodes(nodeIndex1, nodeIndex2)
Description: Given an edge defined by two nodes, returns the list of cells including that edge. If the two nodes do not form a valid edge, returns an empty list.
IMPORTANT: This function should only be called if mesh:hasCapability("topology") returns true.
Parameters: nodeIndex1 The first node index (a value from 1 to mesh:numNodes() - the given node can not be a ghost node).
nodeIndex2 The second node index (a value from 1 to mesh:numNodes() - the given node can not be a ghost node).
Returns: Returns a list (table) filled with the set of adjacent cell objects to the given edge.

Example:

-- Get the adjacents cell to the 5, 8 node pair
local adjCells = m:edgeAdjacentCellsFromNodes(5, 8)


mesh:isBorderNode(nodeIndex)
Description: Returns true if this node belongs to any edge or face that does not have an adjacent cell. Returns false otherwise (this includes nodes that do not belong to any cell or belonging only to non manifold cells - bars or surface cells in a solid mesh).
IMPORTANT: This function should only be called if mesh:hasCapability("topology") returns true.
Parameters: nodeIndex - The node index (a value from 1 to mesh:numNodes() - the given node can not be a ghost node).
Returns: Returns true or false defining whether the node is on the mesh border or not.

Example:

-- Is node 5 on the mesh border?
local inBorder = m:isBorderNode(5)


mesh:numBorders()
Description: Returns the number of border curves for a surface mesh (can be greater than 1 if the mesh has holes or is not continuous) or border surfaces for a solid mesh (can be greater than 1 if the solid has internal hollow parts or is not continuous).
IMPORTANT: This function should only be called if mesh:hasCapability("topology") returns true.
Parameters: None.
Returns: The number of border curves for a surface mesh or surfaces for a solid mesh.

Example:

local nborders = m:numBorders()


mesh:borderIndex(cellIndex, sideIndex)
mesh:borderIndex(cell, sideIndex)
Description: Given a cell (defined either by its index or by a cell object) and a cell side index (edge index for surface elements or face index for solid elements), returns the associated border index (a value between 1 and mesh:numBorders()) for border sides, 0 for a border side that belongs to a topological "hole" in the mesh created by the intersection of multiple interface elements, -1 for internal sides and -2 for "strange" elements (bars on a surface mesh, bars or surface elements on a solid mesh).
IMPORTANT: This function should only be called if mesh:hasCapability("topology") returns true.
Parameters: cellIndex The cell id number (an index between 1 and mesh:numCells()).
cell The cell object.
sideIndex The index of the side whose border index will be queried. It should be an edge local index (a value between 1 and geometry:numEdges()) for surface elements and a face local index (a value between 1 and geometry:numFaces()) for solid elements. See the Element types page for the edge and face organization for each cell type.
Returns: Returns either a border index (a value between 1 and mesh:numBorders()) or a value less or equal to zero as detailed on the method description above.

Example:

-- Get the border index of the second edge of the first mesh cell
local border = m:borderIndex(1, 2)


mesh:firstBorderCurveEdge(borderIndex)
Description: Given a border curve index from a surface mesh, returns a mesh edge belonging to that border. The returned edge is specified by a cell object and the local edge index inside that cell.
IMPORTANT: This function should only be called if mesh:hasCapability("topology") returns true.
Also consider using the more modern API given by calls to the borderTraverseXxx() family of functions. Those functions also support solid meshes.
Parameters: borderIndex - The border index (a value from 1 to mesh:numBorders()). Can also be obtained from a call to mesh:borderIndex().
Returns: Returns a cell object and the local edge index for an edge belonging to the specified mesh border.

Example:

-- Given a surface mesh m, prints border edges by traversing the border information
function printSurfaceMeshBorders(m)
for i = 1, m:numBorders() do
print('-- Border '..i)
local firstCell, firstEdge = m:firstBorderCurveEdge(i)
print(string.format('%d, %d', firstCell:id(), firstEdge))
local cell, edge = m:nextBorderCurveEdge(firstCell, firstEdge)
while cell:id() ~= firstCell:id() or edge ~= firstEdge do
print(string.format('%d, %d', cell:id(), edge))
cell, edge = m:nextBorderCurveEdge(cell, edge)
end
end
end


mesh:nextBorderCurveEdge(cellIndex, edgeIndex)
mesh:nextBorderCurveEdge(cell, edgeIndex)
Description: Given a "current" cell edge belonging to a border from a surface mesh, returns the next edge in the border. The current edge is specified by either a cell object or a cell id and the local edge index inside the cell. Those input parameters should be the values returned by mesh:firstBorderCurveEdge() or by a previous call to mesh:nextBorderCurveEdge(). The example shows how this two methods can be combined to traverse a mesh border. The returned edge is specified by a cell object and the local edge index inside that cell.
IMPORTANT: This function should only be called if mesh:hasCapability("topology") returns true.
Also consider using the more modern API given by calls to the borderTraverseXxx() family of functions. Those functions also support solid meshes.
Parameters: cellIndex The current cell id number (an index between 1 and mesh:numCells()).
cell The current cell object.
edgeIndex The current index of the edge. It should be an edge local index (a value between 1 and geometry:numEdges()). See the Element types page for the edge organization for each cell type.
Returns: Returns a cell object and the local edge index for the next edge in the mesh border containing the current edge, provided as input to the call. Edges from the outter mesh border are traversed in CCW (counter clock-wise) order and edges from internal borders (holes) are traversed in CW (clock-wise) order.

Example:

-- Given a surface mesh m, prints border edges by traversing the border information
function printSurfaceMeshBorders(m)
for i = 1, m:numBorders() do
print('-- Border '..i)
local firstCell, firstEdge = m:firstBorderCurveEdge(i)
print(string.format('%d, %d', firstCell:id(), firstEdge))
local cell, edge = m:nextBorderCurveEdge(firstCell, firstEdge)
while cell:id() ~= firstCell:id() or edge ~= firstEdge do
print(string.format('%d, %d', cell:id(), edge))
cell, edge = m:nextBorderCurveEdge(cell, edge)
end
end
end


mesh:borderTraverseStart(borderIndex)
Description: Initializes the traversal of a surface or solid mesh border. The example shows how borderTraverseStart(), borderTraverseNext() and borderTraverseEnd() can be combined to traverse all edges or faces from the border of either a surface or solid mesh.
IMPORTANT: This function should only be called if mesh:hasCapability("topology") returns true.
Parameters: borderIndex - The index of the border to be traversed (a value from 1 to mesh:numBorders()). Can be obtained from a call to mesh:borderIndex().
Returns: Returns the context that should be used as parameter in calls to mesh:borderTraverseNext(context) and mesh:borderTraverseEnd(context).

Example:

-- Given a mesh m, prints border edges or faces by traversing the border information
function printMeshBorders(m)
for i = 1, m:numBorders() do
print('-- Border '..i)
local context = m:borderTraverseStart(i)
local cell, side = m:borderTraverseNext(context)
while cell do
print(string.format('%d, %d', cell:id(), side))
cell, side = m:borderTraverseNext(context)
end
m:borderTraverseEnd(context)
end
end


mesh:borderTraverseNext(context)
Description: Returns the next side (edge or face) from the border. The example shows how borderTraverseStart(), borderTraverseNext() and borderTraverseEnd() can be combined to traverse all edges or faces from the border of either a surface or solid mesh.
IMPORTANT: This function should only be called if mesh:hasCapability("topology") returns true.
Parameters: context - The context returned by the call to mesh:borderTraverseStart().
Returns: Returns a cell object and the local edge or face index for the next edge or face in the mesh border. Returns nil if the traversal has ended (no more sides to return).

Example:

-- Given a mesh m, prints border edges or faces by traversing the border information
function printMeshBorders(m)
for i = 1, m:numBorders() do
print('-- Border '..i)
local context = m:borderTraverseStart(i)
local cell, side = m:borderTraverseNext(context)
while cell do
print(string.format('%d, %d', cell:id(), side))
cell, side = m:borderTraverseNext(context)
end
m:borderTraverseEnd(context)
end
end


mesh:borderTraverseEnd(context)
Description: Finishes the border traversal, releasing the context (which should NOT be used anymore). The example shows how borderTraverseStart(), borderTraverseNext() and borderTraverseEnd() can be combined to traverse all edges or faces from the border of either a surface or solid mesh.
IMPORTANT: This function should only be called if mesh:hasCapability("topology") returns true.
Parameters: context - The context returned by the call to mesh:borderTraverseStart().
Returns: Nothing.

Example:

-- Given a mesh m, prints border edges or faces by traversing the border information
function printMeshBorders(m)
for i = 1, m:numBorders() do
print('-- Border '..i)
local context = m:borderTraverseStart(i)
local cell, side = m:borderTraverseNext(context)
while cell do
print(string.format('%d, %d', cell:id(), side))
cell, side = m:borderTraverseNext(context)
end
m:borderTraverseEnd(context)
end
end


mesh:hasElementsWithoutTopology()
Description: Returns true if the mesh includes elements without topology support (non-manifold elements like bars for a surface mesh or bars, quads and triangles for solid meshes), false otherwise.
IMPORTANT: This function should only be called if mesh:hasCapability("topology") returns true.
Parameters: None.
Returns: Returns true or false.

Example:

print(m:hasElementsWithoutTopology())


mesh:hasSolidElements()
Description: Returns true if the mesh includes solid elements, false otherwise. Notice that, in a generic setting, one can not just query coordinate dimensions since there is support for surface meshes with 3d coordinates.
IMPORTANT: This function should only be called if mesh:hasCapability("topology") returns true.
Parameters: None.
Returns: Returns true or false.

Example:

print(m:hasSolidElements())


mesh:clearTopology()
Description: If the mesh has an associated topology structure, gives a hint to the mesh that the topology information will not be needed anymore and can be removed, if at all possible.
Parameters: None.
Returns: None.

Example:

m:clearTopology()


Cell data methods

mesh:cellValueIds(filter)
Description: Returns a list with the name (id) of cell state variables and/or cell attributes associated with the mesh. The optional filter parameter defines if the returned list will be filled with state variable names, cell attribute names or both (in that order).
Parameters: filter - The optional filter. Can be either "sv" to include only cell state variables in the list or "attr" to include only cell attributes. If missing, both will be included.
Returns: Returns a table with cell state variable and/or attribute ids (strings).

Example:

local cellValueIds = m:cellValueIds()
local cellAttrIds = m:cellValueIds('attr')
local cellSvIds = m:cellValueIds('sv')


mesh:cellValueInfo(name, filter)
Description: Returns an object with metadata information about the named mesh cell value (either a state variable or a cell attribute).
Parameters: name The cell attribute / state variable name (id).
filter An optional filter string. If equal to "sv" and the queried id is not a state variable, returns nil. Similarly, if equal to "attr" and the queried id is not a cell attribute, returns nil. If empty, no filtering is done.
Returns: Returns a value info object or nil if the requested name was not found in the mesh or is in disagreement with the given filter.

Example:

local rhoInfo = m:cellValueInfo('rho')


mesh:cellValueAccessor(name, unit)
mesh:cellValueAccessor(name, state, locked, unit)
Description: Returns a Cell accessor object that can be used to retrieve and update data for cell attributes and cell state variables. Can be called with two different signatures. The first, receiving only the attribute name and an optional unit, always retrieves data from the current state and is the most used. The second, allows for defining the desired state from which data will be recovered / written. As a matter of fact, the first format is equivalent to calling the second one as mesh:cellValueAccessor(name, 0, true, unit).
Parameters: name The name (id) of the cell attribute / state var.
state An optional state number referencing the history state that the accessor will operate on. A value of zero means the most recent state, 1 the previous one, 2 the one before that and so on. Valid values range from zero to the oldest state for the requested variable, which can be queried with a call to mesh:numCellValueStates(). Remember that for a cell accessor to support states, the history parameter must be set on its value info object.
locked The locked parameter controls the behaviour of the accessor once a new state is created for the value. The 'lock' refers to the state number, so if locked is false and a new state is created, the accessor doesn't change and continues to point to the same data. If locked is true, the accessor will be locked to that state number, so when a new state is created, the accessor changes the data its looking upon to reflect the new state. For example, an accessor locked on state 0 will always point to the current state, and one locked to state 1 will always point to the previous saved value.
unit An optional string with the desired unit for returned values. If different from the data unit, the accessor will automatically convert values.
Returns: A Cell accessor object or nil on errors (the requested name is unknown, or the requested unit is incompatible with the data unit, for example).

Example:

local rhoAc = m:cellValueAccessor('rho') -- Get an accessor to the 'rho' cell attribute
local rhoAc2 = m:cellValueAccessor('rho', 'g/cm3') -- Get an accessor to the 'rho' cell attribute with values converted to g/cm3
local rhoAc3 = m:cellValueAccessor('rho', 1, true) -- Get an accessor locked on the previous saved value of attribute 'rho'


mesh:addCellValueSet(valInfo)
Description: Creates a new value set for storing data for a new cell attribute and associates this new attribute with the mesh.
Parameters: valInfo - A new value info object created by a call to ValueInfo(), with valueKind equal to "cell attribute" or "cell state variable".
Returns: Returns true on success, false on error.

Example:

local newInfo = ValueInfo('cell attribute', {id = 'new1', unit = 's'})
assert(m:addCellValueSet(newInfo) == true)


mesh:removeCellValueSet(name)
Description: Removes the named cell attribute from the mesh. Use carefully.
Parameters: name - The name (id) of the cell attribute.
Returns: Nothing.

Example:

m:removeCellValueSet('rho')


mesh:clearCellValueSets()
Description: Removes all cell attributes from the mesh. Use carefully.
Parameters: None.
Returns: Nothing.

Example:

m:clearCellValueSets()


Cell property methods

mesh:cellPropertyInfo(name)
Description: Returns an object with metadata information about the named cell property.
Parameters: name - The property name (id).
Returns: Returns a value info object or nil if the requested name was not found in the mesh.

Example:

local rhoInfo = m:cellPropertyInfo('rho')


mesh:cellPropertyAccessor(name, unit)
Description: Returns a Cell accessor object that can be used to retrieve data for cell properties. Unlike other accessor types, a property accessor always retrieves data from the current state.
Parameters: name The name (id) of the cell property.
unit An optional string with the desired unit for returned values. If different from the data unit, the accessor will automatically convert values.
Returns: A Cell accessor object or nil on errors (the requested name is unknown, or the requested unit is incompatible with the data unit, for example).

Example:

local rhoAc = m:cellPropertyAccessor('rho') -- Get an accessor to the 'rho' cell property
local rhoAc2 = m:cellPropertyAccessor('rho', 'g/cm3') -- Get an accessor to the 'rho' cell property with values converted to g/cm3


mesh:numPropertySets()
Description: Returns the number of property sets attached to this mesh.
Parameters: None.
Returns: Returns the number of property sets.

Example:

local npsets = m:numPropertySets()


mesh:propertySets()
Description: Returns a list with the property set objects attached to this mesh.
Parameters: None.
Returns: Returns a list of property set objects.

Example:

-- Prints the name of the property sets attached to this mesh
local psets = m:propertySets()
for i = 1, #psets do
print(psets[i]:id())
end


mesh:propertySetIndex(name)
Description: Returns the index of the property set that includes the given property name.
Parameters: name - The property name.
Returns: Returns the index inside the list returned by mesh:propertySets() of the property set object that contains 'name' among its properties. Returns nil for unknown names.

Example:

local psetIndex = m:propertySetIndex('rho')


Cell quality methods

mesh:isValid()
Description: Checks the mesh cells validity. The mesh is considered valid if all of its cells are valid according to cell:isValid().

Parameters: | print | (Optional) Boolean if true isValid() will print detailed information for invalid cells. (Default = true) | ^ | tolerance | (Optional) Tolerance used for tests (i.e. planarity). (Default = 1e-3) | Returns: | Returns true if all the mesh cells are valid, false otherwise. |

Example:

if m:isValid() then
...
end
if m:isValid(false, 1.0) then -- no print, tolerance = 1.0
...
end


mesh:edgeMinLength()
Description: Returns the minimum edge length for all edges in the mesh. The returned value is expressed in the mesh coordinates unit and might be an approximation for quadratic elements. The returned statistics are calculated on first usage (of any of the edge or bounding box min/max length functions) and are not updated automatically when cell nodes change or have their coordinates updated. Use mesh:clearCellStatistics() to force an update.
Parameters: None.
Returns: Returns the minimum mesh edge length.

Example:

local minLen = m:edgeMinLength()


mesh:edgeMaxLength()
Description: Returns the maximum edge length for all edges in the mesh. The returned value is expressed in the mesh coordinates unit and might be an approximation for quadratic elements. The returned statistics are calculated on first usage (of any of the edge or bounding box min/max length functions) and are not updated automatically when cell nodes change or have their coordinates updated. Use mesh:clearCellStatistics() to force an update.i
Parameters: None.
Returns: Returns the maximum mesh edge length.

Example:

local maxLen = m:edgeMaxLength()


mesh:cellBboxMinLength()
Description: Among all the cells in the mesh, returns the minimum length of a mesh cell bounding box diagonal. The returned value is expressed in the mesh coordinates unit. The returned statistics are calculated on first usage (of any of the edge or bounding box min/max length functions) and are not updated automatically when cell nodes change or have their coordinates updated. Use mesh:clearCellStatistics() to force an update.
Parameters: None.
Returns: Returns the minimum length of a mesh cell bounding box diagonal.

Example:

local minLen = m:cellBboxMinLength()


mesh:cellBboxMaxLength()
Description: Among all the cells in the mesh, returns the maximum length of a mesh cell bounding box diagonal. The returned value is expressed in the mesh coordinates unit. The returned statistics are calculated on first usage (of any of the edge or bounding box min/max length functions) and are not updated automatically when cell nodes change or have their coordinates updated. Use mesh:clearCellStatistics() to force an update.
Parameters: None.
Returns: Returns the maximum length of a mesh cell bounding box diagonal.

Example:

local maxLen = m:cellBboxMaxLength()


mesh:clearCellStatistics()
Description: Clears the internal statistics returned by the edge and bounding box min/max length functions. This function should be called after mesh geometry changes, if those statistics are being used.
Parameters: None.
Returns: Nothing.

Example:

m:clearCellStatistics()


mesh:printQualityHistogram(activeOnly)
Description: Prints cells quality histogram.
Parameters: activeOnly - If true, only the active cells will be scanned, all of them otherwise. Default = true.
Returns: Nothing.

Example:

m:printQualityHistogram() -- default mode, only considers active cells
m:printQualityHistogram(false) -- quality is evaluated for every cell in the mesh


Cell group methods

mesh:cellGroupIds()
Description: Returns a list with the names of the configured mesh cell groups.
Parameters: None.
Returns: Returns a table with cell group names (can be empty).

Example:

-- Prints cell group names
local gids = m:cellGroupIds()
for i = 1, #gids do
print(gids[i])
end


mesh:cellGroupIndex(name)
Description: Returns the index of the given group in the group names list returned by mesh:cellGroupIds().
Parameters: name - The cell group name (id).
Returns: Returns the group index or nil if the given name does not correspond to any mesh cell group.

Example:

local gindex = m:cellGroupIndex('group_name')


mesh:numCellsInGroup(groupIndex)
Description: Given a group index, returns the number of cells in this group.
Parameters: groupIndex - The cell group index (a value between 1 and the number of entries in the list returned by mesh:cellGroupIds()).
Returns: Returns the number of cells in the given group.

Example:

-- Get the number of cells in the group named 'myGroup'
local ncells = m:numCellsInGroup(m:cellGroupIndex('myGroup'))


mesh:cellInGroup(groupIndex, cellIndex)
Description: Returns the cell object given its position inside a cell group.
Parameters: groupIndex The cell group index (a value between 1 and the number of entries in the list returned by mesh:cellGroupIds()).
cellIndex The cell index inside the group (a value between 1 and mesh:numCellsInGroup()).
Returns: Returns the cell object.

Example:

-- Print the id of every cell inside the cell group named 'myGroup'
local gindex = m:cellGroupIndex('myGroup')
for i = 1, m:numCellsInGroup(gindex) do
local c = m:cellInGroup(gindex, i)
print(c:id())
end


mesh:addCellGroup(groupName)
Description: Adds a new (empty) cell group to the mesh. This function can only be called if mesh:hasCapability("editGroups") returns true.
Parameters: groupName The name of the cell group that will be added to the mesh. Must be a new group name.
Returns: Returns the added cell group index (its index in the list returned by mesh:cellGroupIds()) or nil if the group could not be added.

Example:

-- Adds a new cell group called 'new group' to the mesh
m:addCellgroup('new group')


mesh:addCellsToGroup(groupIndex, cellIdList)
mesh:addCellsToGroup(groupIndex, cellRangeList)
Description: Adds a list of cells to the given cell group. Added cells can be given either as a table with cell ids or as a table with sub-tables containing id ranges. This function can only be called if mesh:hasCapability("editGroups") returns true.
Parameters: groupIndex The cell group index (a value between 1 and the number of entries in the list returned by mesh:cellGroupIds()).
cellIdList A table with the cell ids for the cells to be added to the group.
cellRangeList A table with cell id ranges for the cells to be added to the group. Each range is given as a sub-table storing the first and last cell indices in the range.
Returns: Returns true on success, false if it was not possible to add cells to the group.

Example:

-- Adds cells 10, 15 and 18 to the third cell group
m:addCellsToGroup(3, {10, 15, 18})
-- Adds cells 10 to 15 and 18 to 25 to the third cell group
m:addCellsToGroup(3, {{10, 15}, {18, 25}})


mesh:cellBoundaryGroups()
Description: Returns a map storing the configured set of cell boundary objects.
Parameters: None.
Returns: Returns a table indexed by cell boundary group names, with each entry storing a reference to a cell boundary object.

Example:

-- Prints the name and number of cells for each boundary group in the mesh
local boundaries = m:cellBoundaryGroups()
for name, boundary in pairs(boundaries) do
print(name, boundary:numCells())
end


History methods

mesh:saveCellValueState(name, mode)
Description: Saves the current state for the given cell attribute / state var, creating a new current state. The time associated with the new current state is initialized to the value of the current simulation time (set either explicitly by a call to setCurrentTime() or implicitly by some process functions). This can later be changed by a call to mesh:setCellValueStateTime().
Parameters: name The name (id) of the cell attribute.
mode The requested save mode, defining how the new state will be initialized. Can be one of the following strings: "init" (new state is initialized with the data default value), "noinit" (new state is not initialized at all) or "copy" (new state is initialized with a copy of the current state).
Returns: Returns true if successful, false otherwise. In particular, this function returns false if the given attribute does not have history values enabled.

Example:

m:saveCellValueState('rho', 'noinit')


mesh:numCellValueStates(name)
Description: Returns the number of existing history states for the given cell attribute / state var.
Parameters: name - The name (id) of the cell attribute.
Returns: Returns the number of existing states or -1 for unknown names.

Example:

local nstates = m:numCellValueStates('rho')


mesh:cellValueStateTag(name, state)
Description: Returns the tag attached to the requested state, for the given cell attribute / state var.
Parameters: name The name (id) of the cell attribute.
state The state number, referencing the history state to be queried. A value of zero means the most recent state, 1 the previous one, 2 the one before that and so on. Valid values range from zero to the oldest state for the requested attribute, which can be obtained with a call to mesh:numCellValueStates().
Returns: The state tag attached to the requested state or "" if the name doesn't exists.

Example:

local tag = n:cellValueStateTag('rho', 0) -- Tag from the current state
local oldTag = n:cellValueStateTag('rho', 1) -- Tag from the previous state


mesh:cellValueStateTime(name, state)
Description: Returns the time attached to the requested state, for the given cell attribute / state var.
Parameters: name The name (id) of the cell attribute.
state The state number, referencing the history state to be queried. A value of zero means the most recent state, 1 the previous one, 2 the one before that and so on. Valid values range from zero to the oldest state for the requested attribute, which can be obtained with a call to mesh:numCellValueStates().
Returns: The time attached to the requested state or -1 if the name doesn't exists.

Example:

local t = n:cellValueStateTime('rho', 0) -- Time from the current state
local oldt = n:cellValueStateTime('rho', 1) -- Time from the previous state


mesh:setCellValueStateTag(name, state, tag)
Description: Updates the tag attached to the requested state, for the given cell attribute / state var.
Parameters: name The name (id) of the cell attribute.
state The state number, referencing the history state to be queried. A value of zero means the most recent state, 1 the previous one, 2 the one before that and so on. Valid values range from zero to the oldest state for the requested attribute, which can be obtained with a call to mesh:numCellValueStates().
tag The new state tag.
Returns: Nothing.

Example:

m:setCellValueStateTag('rho', 1, 'myTag') -- Updates the tag from the previous state for cell attribute 'rho'


mesh:setCellValueStateTime(name, state, time)
Description: Updates the time attached to the requested state, for the given cell attribute / state var.
Parameters: name The name (id) of the cell attribute.
state The state number, referencing the history state to be queried. A value of zero means the most recent state, 1 the previous one, 2 the one before that and so on. Valid values range from zero to the oldest state for the requested attribute, which can be obtained with a call to mesh:numCellValueStates().
time The new state time, expressed in the same unit as the current simulation time unit.
Returns: Nothing.

Example:

m:setCellValueStateTime('rho', 1, 12.5) -- Updates the time from the previous state for cell attribute 'rho'
Generated on Mon Aug 3 2026 10:00:12 for GeMA by doxygen 1.12.0